/*
 * Copyright 2010-2012 Susanta Tewari. <freecode4susant@users.sourceforge.net>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package bd.org.apache.commons.math.util;

import bd.org.apache.commons.math.exception.MaxCountExceededException;

/**
 * Utility that increments a counter until a maximum is reached, at
 * which point, the instance will by default throw a
 * {@link MaxCountExceededException}.
 * However, the user is able to override this behaviour by defining a
 * custom {@link MaxCountExceededCallback callback}, in order to e.g.
 * select which exception must be thrown.
 *
 * @version $Id$
 * @since 3.0
 */
public class Incrementor {

    /**
     * Current count.
     */
    private int count = 0;

    /**
     * Upper limit for the counter.
     */
    private int maximalCount;

    /**
     * Function called at counter exhaustion.
     */
    private final MaxCountExceededCallback maxCountCallback;

    /**
     * Default constructor.
     * For the new instance to be useful, the maximal count must be set
     * by calling {@link #setMaximalCount(int) setMaximalCount}.
     */
    public Incrementor() {

        this(0);
    }

    /**
     * Defines a maximal count.
     *
     * @param max Maximal count.
     */
    public Incrementor(int max) {

        this(max, new MaxCountExceededCallback() {

            /** {@inheritDoc} */
            @Override
            public void trigger(int max) {

                throw new MaxCountExceededException(max);
            }
        });
    }

    /**
     * Defines a maximal count and a callback method to be triggered at
     * counter exhaustion.
     *
     * @param max Maximal count.
     * @param cb Function to be called when the maximal count has been reached.
     */
    public Incrementor(int max, MaxCountExceededCallback cb) {

        maximalCount     = max;
        maxCountCallback = cb;
    }

    /**
     * Sets the upper limit for the counter.
     * This does not automatically reset the current count to zero (see
     * {@link #resetCount()}).
     *
     * @param max Upper limit of the counter.
     */
    public void setMaximalCount(int max) {

        maximalCount = max;
    }


    /**
     * Gets the upper limit of the counter.
     *
     * @return the counter upper limit.
     */
    public int getMaximalCount() {

        return maximalCount;
    }


    /**
     * Gets the current count.
     *
     * @return the current count.
     */
    public int getCount() {

        return count;
    }


    /**
     * Checks whether a single increment is allowed.
     *
     * @return {@code false} if the next call to {@link #incrementCount(int)
     *         incrementCount} will trigger a {@code MaxCountExceededException},
     *         {@code true} otherwise.
     */
    public boolean canIncrement() {

        return count < maximalCount;
    }


    /**
     * Performs multiple increments.
     * See the other {@link #incrementCount() incrementCount} method).
     *
     * @param value Number of increments.
     */
    public void incrementCount(int value) {

        for (int i = 0; i < value; i++) {

            incrementCount();
        }
    }


    /**
     * Adds one to the current iteration count.
     * At counter exhaustion, this method will call the
     * {@link MaxCountExceededCallback#trigger(int) trigger} method of the
     * callback object passed to the
     * {@link #Incrementor(int, MaxCountExceededCallback) constructor}.
     * If not explictly set, a default callback is used that will throw
     * a {@code MaxCountExceededException}.
     *
     * custom {@link MaxCountExceededCallback callback} has been set at
     * construction.
     */
    public void incrementCount() {

        if (++count > maximalCount) {
            maxCountCallback.trigger(maximalCount);
        }
    }


    /**
     * Resets the counter to 0.
     */
    public void resetCount() {

        count = 0;
    }


    /**
     * Defines a method to be called at counter exhaustion.
     * The {@link #trigger(int) trigger} method should usually throw an exception.
     */
    public interface MaxCountExceededCallback {

        /**
         * Function called when the maximal count has been reached.
         *
         * @param maximalCount Maximal count.
         */
        void trigger(int maximalCount);
    }
}
